/* Microsoft Reference Implementation for TPM 2.0
 *
 *  The copyright in this software is being made available under the BSD License,
 *  included below. This software may be subject to other third party and
 *  contributor rights, including patent rights, and no such rights are granted
 *  under this license.
 *
 *  Copyright (c) Microsoft Corporation
 *
 *  All rights reserved.
 *
 *  BSD License
 *
 *  Redistribution and use in source and binary forms, with or without modification,
 *  are permitted provided that the following conditions are met:
 *
 *  Redistributions of source code must retain the above copyright notice, this list
 *  of conditions and the following disclaimer.
 *
 *  Redistributions in binary form must reproduce the above copyright notice, this
 *  list of conditions and the following disclaimer in the documentation and/or
 *  other materials provided with the distribution.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ""AS IS""
 *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 *  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
 *  ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 *  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 *  ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 *  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
#include "Tpm.h"
#include "CreateLoaded_fp.h"

#if CC_CreateLoaded  // Conditional expansion of this file

/*(See part 3 of specification)
 * Create and load any type of key, including a temporary key.
 * The input template is a marshaled public area rather than an unmarshaled one as
 * used in Create and CreatePrimary. This is so that the label and context that
 * could be in the template can be processed without changing the formats for the
 * calls to Create and CreatePrimary.
*/
//  Return Type: TPM_RC
//      TPM_RC_ATTRIBUTES       'sensitiveDataOrigin' is CLEAR when 'sensitive.data'
//                              is an Empty Buffer;
//                              'fixedTPM', 'fixedParent', or 'encryptedDuplication'
//                              attributes are inconsistent between themselves or with
//                              those of the parent object;
//                              inconsistent 'restricted', 'decrypt' and 'sign'
//                              attributes;
//                              attempt to inject sensitive data for an asymmetric
//                              key;
//                              attempt to create a symmetric cipher key that is not
//                              a decryption key
//      TPM_RC_KDF              incorrect KDF specified for decrypting keyed hash
//                              object
//      TPM_RC_KEY              the value of a provided symmetric key is not allowed
//      TPM_RC_OBJECT_MEMORY    there is no free slot for the object
//      TPM_RC_SCHEME           inconsistent attributes 'decrypt', 'sign',
//                              'restricted' and key's scheme ID; or hash algorithm is
//                              inconsistent with the scheme ID for keyed hash object
//      TPM_RC_SIZE             size of public authorization policy or sensitive
//                              authorization value does not match digest size of the
//                              name algorithm sensitive data size for the keyed hash
//                              object is larger than is allowed for the scheme
//      TPM_RC_SYMMETRIC        a storage key with no symmetric algorithm specified;
//                              or non-storage key with symmetric algorithm different
//                              from TPM_ALG_NULL
//      TPM_RC_TYPE             cannot create the object of the indicated type
//                              (usually only occurs if trying to derive an RSA key).
/*
Part3,12.9 TPM2_CreateLoaded
This command creates an object and loads it in the TPM. 
This command allows creation of any type of object (Primary, Ordinary, or Derived) depending on the type of parentHandle. 
If parentHandle references a Primary Seed, then a Primary Object is created; if parentHandle references a Storage Parent, 
then an Ordinary Object is created; and if parentHandle references a Derivation Parent, then a Derived Object is generated.
此命令创建一个对象并将其加载到 TPM 中。
此命令允许根据 parentHandle 的类型创建任何类型的对象（Primary、Ordinary 或 Derived）。
如果 parentHandle 引用了一个 Primary Seed，那么就会创建一个 Primary Object； 如果 parentHandle 引用一个 Storage Parent，则创建一个普通对象； 
如果 parentHandle 引用派生父对象，则生成派生对象.

The input validation is the same as for TPM2_Create() and TPM2_CreatePrimary() with one exception:
when parentHandle references a Derivation Parent, then sensitiveDataOrigin in inPublic is required to be CLEAR.
输入验证与 TPM2_Create() 和 TPM2_CreatePrimary() 相同，但有一个例外：
当 parentHandle 引用 Derivation Parent 时，inPublic 中的 sensitiveDataOrigin 需要是 CLEAR。
TODO: what is Derivation Parent？

Note 1 In the general descriptions of TPM2_Create() and TPM2_CreatePrimary() the validations refer to a TPMT_PUBLIC structure that is in inPublic. 
For TPM2_CreateLoaded(), inPublic is a TPM2B_TEMPLATE that may contain a TPMT_PUBLIC that is used for object creation. 
For object derivation, the unique field can contain a label and context that are used in the derivation process.
To allow both the TPMT_PUBLIC and the derivation variation, a TPM2B_TEMPLATE is used. 
When referring to the checks in TPM2_Create() and TPM2_CreatePrimary(), TPM2B_TEMPLATE should be assumed to contain a TPMT_PUBLIC.
注 1 在 TPM2_Create() 和 TPM2_CreatePrimary() 的一般描述中，验证指的是 inPublic 中的 TPMT_PUBLIC 结构。
对于 TPM2_CreateLoaded()，inPublic 是一个 TPM2B_TEMPLATE，它可能包含一个用于创建对象的 TPMT_PUBLIC。
对于对象派生，唯一字段可以包含在派生过程中使用的标签和上下文。
为了允许 TPMT_PUBLIC 和派生变体，使用了 TPM2B_TEMPLATE。
当提及 TPM2_Create() 和 TPM2_CreatePrimary() 中的检查时，应假定 TPM2B_TEMPLATE 包含 TPMT_PUBLIC。

If parentHandle references a Derivation Parent, then the TPM may return TPM_RC_TYPE if the key type to be generated is an RSA key.
If parentHandle references a Derivation Parent or a Primary Seed, then outPrivate will be an Empty Buffer.
如果 parentHandle 引用 Derivation Parent，并且要生成的密钥类型是 RSA 密钥，则 TPM 可能会返回 TPM_RC_TYPE。
如果 parentHandle 引用 Derivation Parent 或 Primary Seed，则 outPrivate 将是一个空缓冲区。

NOTE 2 Returning outPrivate would imply that the returned primary or derived object can be loaded and it cannot. It can only be re-derived.

A primary key cannot be loaded is because loading a key is a way to attack the protections of a key (e.g. using DPA).
A saved context for a primary object is protected. The TPM will go into failure mode if the integrity of a saved context is good but 
the fingerprint doesn’t decrypt. It is not possible to have these protections on loaded objects because this would be a simple way for an attacker 
to put the TPM into failure mode Saved contexts are assumed to be under control of the driver but loaded objects are not.

If all objects were derived from their parents then, load could not be used as an attack. However, that would preclude importation of objects and key hierarchies.
注 2 返回 outPrivate 意味着可以加载返回的主对象或派生对象，但不能。 只能重新派生。

无法加载主键是因为加载密钥是攻击密钥保护的一种方式（例如使用 DPA）。
主要对象的已保存上下文受到保护。 如果保存的上下文完整性良好但指纹未解密，则 TPM 将进入故障模式。 不可能对加载的对象进行这些保护，因为这将是攻击者将 TPM 置于故障模式的简单方法。
保存的上下文被假定为在驱动程序的控制下，但加载的对象不是。

如果所有对象都是从它们的父对象派生的，那么负载就不能用作攻击。 但是，这将排除对象和密钥层次结构的导入。

NOTE 3 Unlike TPM2_Create() and TPM2_CreatePrimary(), this command does not return creation data(创建数据). If
creation data is needed, then TPM2_Create() or TPM2_CreatePrimary() should be used.
 */
TPM_RC
TPM2_CreateLoaded(
    CreateLoaded_In    *in,            // IN: input parameter list
    CreateLoaded_Out   *out            // OUT: output parameter list
    )
{
    TPM_RC                       result = TPM_RC_SUCCESS;
    OBJECT                      *parent = HandleToObject(in->parentHandle);
    OBJECT                      *newObject;
    BOOL                         derivation;
    TPMT_PUBLIC                 *publicArea;
    RAND_STATE                   randState;
    RAND_STATE                  *rand = &randState;
    TPMS_DERIVE                  labelContext;

// Input Validation

    // How the public area is unmarshaled is determined by the parent, so
    // see if parent is a derivation parent
    derivation = (parent != NULL && parent->attributes.derivation);

    // If the parent is an object, then make sure that it is either a parent or
    // derivation parent
    if(parent != NULL && !parent->attributes.isParent && !derivation)
        return TPM_RCS_TYPE + RC_CreateLoaded_parentHandle;

    // Get a spot in which to create the newObject
    newObject = FindEmptyObjectSlot(&out->objectHandle);
    if(newObject == NULL)
        return TPM_RC_OBJECT_MEMORY;

    // Do this to save typing
    publicArea = &newObject->publicArea;

    // Unmarshal the template into the object space. TPM2_Create() and
    // TPM2_CreatePrimary() have the publicArea unmarshaled by CommandDispatcher.
    // This command is different because of an unfortunate property of the
    // unique field of an ECC key. It is a structure rather than a single TPM2B. If
    // if had been a TPM2B, then the label and context could be within a TPM2B and
    // unmarshaled like other public areas. Since it is not, this command needs its
    // on template that is a TPM2B that is unmarshaled as a BYTE array with a
    // its own unmarshal function.
    // 从输入二进制缓冲区中反序列化出 publicArea
    result = UnmarshalToPublic(publicArea, &in->inPublic, derivation,
                               &labelContext);
    if(result != TPM_RC_SUCCESS)
        return result + RC_CreateLoaded_inPublic;

    // Validate that the authorization size is appropriate
    if(!AdjustAuthSize(&in->inSensitive.sensitive.userAuth, publicArea->nameAlg))
        return TPM_RCS_SIZE + RC_CreateLoaded_inSensitive;

    // Command output
    // derivation for 派生
    if(derivation)
    {
        TPMT_KEYEDHASH_SCHEME       *scheme;
        scheme = &parent->publicArea.parameters.keyedHashDetail.scheme;

        // SP800-108 is the only KDF supported by this implementation and there is
        // no default hash algorithm.
        pAssert(scheme->details.xor.hashAlg != TPM_ALG_NULL
                && scheme->details.xor.kdf == TPM_ALG_KDF1_SP800_108);
        // Don't derive RSA keys
        if(publicArea->type == TPM_ALG_RSA)
            return TPM_RCS_TYPE + RC_CreateLoaded_inPublic;
        // sensitiveDataOrigin has to be CLEAR in a derived object. Since this
        // is specific to a derived object, it is checked here.
        if(IS_ATTRIBUTE(publicArea->objectAttributes, TPMA_OBJECT,
                        sensitiveDataOrigin))
            return TPM_RCS_ATTRIBUTES;
        // Check the reset of the attributes
        result = PublicAttributesValidation(parent, publicArea);
        if(result != TPM_RC_SUCCESS)
            return RcSafeAddToResult(result, RC_CreateLoaded_inPublic);
        // Process the template and sensitive areas to get the actual 'label' and
        // 'context' values to be used for this derivation.
        result = SetLabelAndContext(&labelContext, &in->inSensitive.sensitive.data);
        if(result != TPM_RC_SUCCESS)
            return result;
        // Set up the KDF for object generation
        DRBG_InstantiateSeededKdf((KDF_STATE *)rand,
                                  scheme->details.xor.hashAlg,
                                  scheme->details.xor.kdf,
                                  &parent->sensitive.sensitive.bits.b,
                                  &labelContext.label.b,
                                  &labelContext.context.b,
                                  TPM_MAX_DERIVATION_BITS);
        // Clear the sensitive size so that the creation functions will not try
        // to use this value.
        in->inSensitive.sensitive.data.t.size = 0;
    }
    else
    {
        // Check attributes in input public area. CreateChecks() checks the things
        // that are unique to creation and then validates the attributes and values
        // that are common to create and load.
        result = CreateChecks(parent, publicArea,
                              in->inSensitive.sensitive.data.t.size);
        if(result != TPM_RC_SUCCESS)
            return RcSafeAddToResult(result, RC_CreateLoaded_inPublic);
        // Creating a primary object
        if(parent == NULL)
        {
            TPM2B_NAME              name;
            newObject->attributes.primary = SET;
            if(in->parentHandle == TPM_RH_ENDORSEMENT)
                newObject->attributes.epsHierarchy = SET;
            // If so, use the primary seed and the digest of the template
            // to seed the DRBG
            // 如果生成主密钥，需要重置随机数生成器
            result = DRBG_InstantiateSeeded((DRBG_STATE *)rand,
                                   &HierarchyGetPrimarySeed(in->parentHandle)->b,
                                   PRIMARY_OBJECT_CREATION,
                                   (TPM2B *)PublicMarshalAndComputeName(publicArea,
                                                                        &name),
                                   &in->inSensitive.sensitive.data.b);
            if(result != TPM_RC_SUCCESS)
                return result;
        }
        else
        {
           // This is an ordinary object so use the normal random number generator
            rand = NULL;
        }
    }
// Internal data update
    // Create the object
    // 生成密钥对，输出到 newObject->sensitive
    result = CryptCreateObject(newObject, &in->inSensitive.sensitive, rand);
    if(result != TPM_RC_SUCCESS)
        return result;
    // if this is not a Primary key and not a derived key, then return the sensitive
    // area
    if(parent != NULL && !derivation)
        // Prepare output private data from sensitive
        SensitiveToPrivate(&newObject->sensitive, &newObject->name,
                           parent, newObject->publicArea.nameAlg,
                           &out->outPrivate);
    else
    // 非可派生主密钥，不能导出到 TPM 外部
        out->outPrivate.t.size = 0;
    // Set the remaining return values
    out->outPublic.publicArea = newObject->publicArea;
    out->name = newObject->name;
    // Set the remaining attributes for a loaded object
    ObjectSetLoadedAttributes(newObject, in->parentHandle);

    return result;
}

#endif // CC_CreateLoaded